<?php
// $Id$
/**
 * This file contains {@link QueryResult} which is part of the PHP Content 
 * Repository (phpCR), a derivative of the Java Content Repository JSR-170, and 
 * is licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');


/**
 * A QueryResult object. Returned in an iterator by {@link Query::execute()}
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface QueryResult 
{
   /**
    * Returns a {@link Node} meeting the search criteria. 
    *
    * If the query executed included a full text SEARCH clause then this method
    * returns the parent {@link Node} of the {@link Property} returned by 
    * {@link getProperty()}.
    *
    * @return object
    */
    public function getNode();
    
    
   /**
    * Returns the paths (there may be more than one) of the matching 
    * {@link Node}.
    *
    * This method may be used to avoid the overhead of accessing the matching
    * {@link Node} itself, if only the paths are required.
    *
    * @return object
    *   A {@link StringIterator}
    */
    public function getNodePaths();
    
    
   /**
    * Returns the UUID of the matching {@link Node}. 
    *
    * If the {@link Node} does not have a UUID, it returns NULL.
    *
    * @return string|null
    */
    public function getUUID();
    
    
   /**
    * Returns the matching {@link Property} if the query executed included a 
    * full text SEARCH clause that matched the {@link Property}'s value. 
    *
    * If this method returns a {@link Property}, then the {@link getNode()}
    * method must return that {@link Property}'s parent.
    *
    * If the query did not include a SEARCH clause then this method returns 
    * NULL.
    *
    * @return object|null
    */
    public function getProperty();
    
    
   /**
    * Returns the name of a {@link Property} retrieved by {@link getProperty()}
    *
    * This method may be used to avoid the overhead of accessing the matching
    * property itself, if only the name is required. 
    *
    * If the query did not include a SEARCH clause then this method returns 
    * NULL.
    *
    * @return string|null
    */
    public function getPropertyName();
    
    
   /**
    * The relevance of this QueryResult. 
    *
    * The details of this metric are implementation specific. The only 
    * requirement is that the returned integer must be equal to or greater than
    * zero (i >= 0) and that higher score number means "more relevant". 
    *
    * Implementations that do not support this metric are free to return a 
    * score of zero (0) for every {@link QueryResult}.
    *
    * If the JCRQL clause ORDER BY SCORE was invoked (or a similar directive
    * in another language) then the QueryResultIterator returned by
    * {@link Query::execute()} must order its returned {@link QueryResult} 
    * objects accordingly, using this score value.
    *
    * @return int
    */
    public function getScore();
}

